<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2008 XBRL International. All Rights Reserved. -->
<?xml-stylesheet type="text/xsl" href="../stylesheets/functionDefinition.xsl"?>
<function
  xmlns="http://xbrl.org/2008/function" 
  xmlns:reg="http://xbrl.org/2008/registry" 
  xmlns:xhtml="http://www.w3.org/1999/xhtml" 
  xmlns:xfi="http://www.xbrl.org/2008/function/instance"
  xmlns:xfie="http://www.xbrl.org/2008/function/instance/error"
  xmlns:xbrli="http://www.xbrl.org/2003/instance" 
  xmlns:xlink="http://www.w3.org/1999/xlink" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xsi:schemaLocation="
  http://xbrl.org/2008/registry ../schemas/registry.xsd
  http://xbrl.org/2008/function ../schemas/function.xsd
  ">

  <lastUpdated moment="2008-12-12T00:00:00" />

  <owners>
    <reg:owner id="herm">
       <reg:name>Herm Fischer</reg:name>
      <reg:affiliation>UBMatrix / Mark V Systems</reg:affiliation>
       <reg:email>fischer@markv.com</reg:email>
       <reg:assumedOwnership moment="2008-09-01T00:00:00" />
    </reg:owner>
  </owners>

  <summary>
    Returns a sequence containing the set of
    QNames representing the concepts that have the specified relationship
    to the source concept.
    The set of dimension member QNames is in an arbitrary order (not
    necessarily that of effective tree relationships order).
  </summary>

  <documentation>
    This directory provides two test case files, one for function testing and one for formula testing.  The formula test cases are helpful examples for tree walks, two alternative forms of calculation linkbase validation, Charlie Hoffman's movement example validation, and xbrl-us preview-2009 movement and total validation.
  </documentation>

  <signature name="xfi:navigate-relationships">

    <input name="source" type="xs:QName">
      <xhtml:p>
        The QName of the source concept from which to begin navigation. 
      </xhtml:p>
      <xhtml:p>
        The special QName xfi:root is recognized when it is desired 
        to retrieve descendants from the 'root' level (who have no parents).
      </xhtml:p>
    </input>

    <input name="linkrole" type="xs:anyURI">
      <xhtml:p>
        The linkrole value that specifies the network of effective
        relationships to determine the selected members on the specified
        axis from the member used as the origin.
      </xhtml:p>
      <xhtml:p>
        If omitted ("()" or "''") then the default link role is used. 
      </xhtml:p>
    </input>

    <input name="arcrole" type="xs:anyURI">
      <xhtml:p>
        The arcrole value that specifies the network of effective
        relationships as above.
      </xhtml:p>
    </input>

    <input name="axis" type="xs:string">
      <xhtml:p>
        The axis value MUST be one of:
      </xhtml:p>
      <xhtml:ul>
        <xhtml:li>descendant-or-self</xhtml:li>
        <xhtml:li>descendant</xhtml:li>
        <xhtml:li>ancestor-or-self</xhtml:li>
        <xhtml:li>ancestor</xhtml:li>
        <xhtml:li>sibling</xhtml:li>
        <xhtml:li>sibling-or-self</xhtml:li>
        <xhtml:li>sibling-or-abstract-descendant</xhtml:li>
      </xhtml:ul>

      <xhtml:p>
        If the axis value is 'descendant' then the filter-member set includes those concepts that are descendants of the source concept QName, in the linkrole network of arcrole effective relationships.  (For child, use descendant and generations = 1.)  For the special sourcd QName xfi:root, descendants are those from the topmost level (those with no parents).
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'descendant-or-self' then the filter-member set includes includes the source concept and those concepts in the explicit dimension domain that are descendants of the concept QName, in the linkrole network of arcrole effective relationships.
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'ancestor' then the filter-member set includes those concepts that are ancestors of the source concept QName, in the linkrole network of arcrole effective relationships.  (For parent, use ancestor and generations = 1.)
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'ancestor-or-self' then the filter-member set includes includes the source concept and those concepts in the explicit dimension domain that are ancestors of the concept QName, in the linkrole network of arcrole effective relationships.
      </xhtml:p>
  
      <xhtml:p>
        If the axis value is 'sibling' then the filter-member set includes those concepts that are siblings of the source concept QName, in the linkrole network of arcrole effective relationships. A sibling is defined as other children of the same parent, unless the concept is root level, then it is other root concepts.
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'sibling-or-self' then it is the source concept and its siblings.
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'sibling-or-abstract-descendant' then it is the source concept and its siblings, plus in addition for any abstract concept the children and recursively children of any abstract children.
      </xhtml:p>

      <xhtml:p>
        If the axis value is 'sibling then the filter-member set includes those concepts that are siblings of the source concept QName, in the linkrole network of arcrole effective relationships.   
      </xhtml:p>
    </input>

    <input name="generations" type="xs:integer">
      <xhtml:p>
        The arcrole value that specifies a limit of number of generations (for descendant or ancestor), or zero (if unlimited generations navigation is desired.  Generations=1 and descendant axis means obtain only children, generations=2 obtains children and grandchildren, and generations=0 means all descendants.
      </xhtml:p>
      <xhtml:p>
        Generations must be 1 for a sibling or sibling-or-self axis.
      </xhtml:p>
      <xhtml:p>
        In any case if a descendant or ancestor concept repeats in the path from the source, it is not navigated further for unlimited generations navigation (generations=0), but it is navigated further for limited generations navigation.  Thus it is not wise to put a high integer on generations count if directed cycles may exist.  A demonstration of this issue is in function test cases v-09 and V-09a. In V-09 navigation starts at A1, for descendants (not self) for unlimited generations.  In this case A1 is not included first in the output (because of missing '-or-self') but A1 is a descendant of A13 (A1-&gt;A13-&gt;A1) so the A1 occurence under A13 is included in the output, but no further navigation from the repeat (directed cycle) beneath A1 is navigated.  In V-09A 7 generations are requested, to show that the directed cycle is followed for 7 generations.
      </xhtml:p>
    </input>

    <input name="arcattributes" type="xs:QName*">
      <xhtml:p>
        This parameter is optional.  If omitted (or empty sequence) no arc attributes are returned.
        If provided the sequence has QNames of arc attributes to be returned with the sequence of concepts QNames.
        For example for preferredLabel of a presentation arc, specify QName('','preferredLabel), or weight of
        a calculation arc, QName('','weight').  Each arc attribute with a value has the type according to the Post Schema
        Validation Infoset, e.g., preferredLabel is an xs:anyURI and weight is an xs:decimal.
        (This version provides for empty string results when the attribute does not exist, to allow
        comparison of preferredLabel attribute and other string attributes that are optional.)
      </xhtml:p>
    </input>

    <input name="xbrlinstance" type="element(xbrli:xbrl)">
      <xhtml:p>
        This parameter is optional.  If absent the target XBRL instance provides the DTS for linkbases containing
        the specified arcrole.  If provided then arcattribute must also be provided (it can be specified "(),").
        If provided then the specified XBRL instance provides the DTS for the relationship linkbases (such as an
        instance dynamically loaded by the xbrl-instance function.)
      </xhtml:p>
      <xhtml:p>
        Conformance tests of this parameter are in directory 90601 xfi.xbrl-instance.
      </xhtml:p>
    </input>

    <output type="xs:anyAtomicType*">
      <xhtml:p>
        Returns a sequence of the concept QNames, and arc attribute values.  If arcattribute(s)
        are not requested then this is just a sequence of QNames.  If arcattributes are returned they
        are consecutive subsequences of the qnames, the first attribute values, the next attribute values, etc.
        E.g., the sequence concept-1-qname, concept-2-qname, concept-1-attr-1-value, concept-2-attr-1-value, 
        concept-1-attr-2-value, concept-2-attr-2-value, etc.  Absent attributes return as an empty string, 
        because if an empty sequence were instead returned, it would be dropped by the union operator and prevent
        iterating through the sequence of results.
      </xhtml:p>
      <xhtml:p>
        The concept QNames are atomic typed xs:QName objects.  The arc attribute values are typed according to the Post Schema Validation Infoset of the DTS of the instance document, so that calculation arc weight is typed xs:decimal, and preferredLabel is typed xs:anyURI (not untyped or xs:string).
      </xhtml:p>
      <xhtml:p>
        The order within each subsequence (QNames subsequence and any subsequent subsequences of arc attribute values) 
        is the effective relationships order after consideration of arc order value, prohibition, and override.
      </xhtml:p>
      <xhtml:p>
        The tree-walk of multiple generations is in depth-first order (or the inverse for ancestors), a node's descendants are recursively inserted in the result subsequences prior to continuing with siblings.
      </xhtml:p>
    </output>
  </signature>

  <conformanceTest xlink:type="simple" xlink:href="90502 xfi.navigate-relationships function testcase.xml"/>

  <revisions>
    <reg:revision on="2008-12-12T00:00:00" by="herm">
      <xhtml:p>
        Created the function definition.
      </xhtml:p>
    </reg:revision>
  </revisions>

</function>
